.TH std::basic_string::insert_range 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary"
.SH NAME
std::basic_string::insert_range \- std::basic_string::insert_range

.SH Synopsis
   template< container-compatible-range<CharT> R >                 (since C++23)
   constexpr iterator insert_range( const_iterator pos, R&& rg );

   Inserts characters from the range rg before the element (if any) pointed by pos.

   Equivalent to

 return insert(pos - begin(),
     std::basic_string(
         std::from_range,
         std::forward<R>(rg),
         get_allocator())
 );

   If pos is not a valid iterator on *this, the behavior is undefined.

.SH Parameters

   pos - iterator before which the characters will be inserted
   rg  - a container compatible range

.SH Return value

   An iterator which refers to the first inserted character, or pos if no characters
   were inserted because rg was empty.

.SH Complexity

   Linear in size of rg.

.SH Exceptions

   If std::allocator_traits<Allocator>::allocate throws an exception, it is rethrown.

   If the operation would result in size() > max_size(), throws std::length_error.

   If an exception is thrown for any reason, this function has no effect (strong
   exception safety guarantee).

.SH Notes

       Feature-test macro       Value    Std                   Feature
   __cpp_lib_containers_ranges 202202L (C++23) member functions that accept container
                                               compatible range

.SH Example


// Run this code

 #include <cassert>
 #include <iterator>
 #include <string>

 int main()
 {
     const auto source = {'l', 'i', 'b', '_'};
     std::string target{"__cpp_containers_ranges"};
     //                        ^insertion will occur
     //                         before this position

     const auto pos = target.find("container");
     assert(pos != target.npos);
     auto iter = std::next(target.begin(), pos);

 #ifdef __cpp_lib_containers_ranges
     target.insert_range(iter, source);
 #else
     target.insert(iter, source.begin(), source.end());
 #endif

     assert(target == "__cpp_lib_containers_ranges");
     //                      ^^^^
 }

.SH See also

   insert inserts characters
          \fI(public member function)\fP
